Inside Macintosh: QuickDraw GX Objects /

Chapter 4 - Colors and Color-Related Objects / Colors and Color-Related Objects Reference

Color Functions /

GXConvertColor

You can use the GXConvertColor function to convert a color from one color space to another.

gxColor *GXConvertColor(gxColor *target, gxColorSpace space, 
                         gxColorSet aSet, gxColorProfile profile);

target

A pointer to the color to be converted. On return, target points to the converted color.

space

The color space to convert the target color to.

aSet

A reference to the color set to assign to the color space of the target color. This parameter must be nil if the space parameter is not gxIndexedSpace.

profile

A reference to the color profile to assign to the converted color (that is, to use as the destination profile for the conversion). If you pass nil for this parameter, QuickDraw GX uses the default color profile.

function result

A pointer to the converted color.

DESCRIPTION

The GXConvertColor function converts a color from one color space to another. The target color is both the input and the output color for this function; the function modifies the target color to reflect the conversion and also returns a pointer to the converted color. If target is nil, the function posts an error and returns nil.

If appropriate, GXConvertColor automatically performs color matching when converting the color. The color profile--if any--associated with the target color is used to correct the input color, and the color profile referenced in the profile parameter--if any--is used to create the final output color. If either color profile is nil, QuickDraw GX uses the default color profile in its place.

When converting to an indexed color space, GXConvertColor uses the color set specified by the aSet parameter as the color set for the returned color. It returns the closest existing color in the color set.

When converting from a color space without an alpha channel to one with an alpha channel, GXConvertColor gives the alpha channel value maximum opacity. When converting from a color space with an alpha channel to one without an alpha channel, the alpha-channel value is lost.

When converting from a color space with colors to a luminance-based (grayscale) color space, the color information is lost but GXConvertColor preserves luminance (overall lightness or brightness).

When converting between color spaces with different color packings (as from gxRGB32Space to gxRGB16Space or gxRGBSpace), GXConvertColor truncates or expands individual color-component values as appropriate.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
color_is_nil
colorSpace_out_of_range	(debugging version)
Warnings
colorSet_index_out_of_range

SEE ALSO

Color spaces are described in the section "Color Spaces" beginning on page 4-6. Color matching is described in the section "Color Conversion and Color Matching" beginning on page 4-26, and in the section "Converting and Matching Colors" beginning on page 4-41.